Cream of the Crop 1

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / CDOS10.ARJ / USERDOC.TXT < prev

Wrap

Text File | 1992-07-07 | 62KB | 2,073 lines

▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒████████▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒████████████▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒█████ ████ ▒▒▒▒█████▒▒▒██████▒▒██████▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒████ ▒▒▒▒ ▒▒▒▒██ ██▒▒██ ██ ▒██ ▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒████ ▒▒▒▒▒▒▒▒▒▒▒▒▒██ ▒██ ▒██ ▒██ ▒▒ ▒██▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒█████▒▒▒▒████▒▒▒▒▒█████ ▒██████ ▒██████ ▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒████████████ ▒▒▒▒▒ ▒▒▒ ▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ████████ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒█▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀█▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒█ The LIBerator 1.0 █ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒█▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄█ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ The reliable C library of functions, for the DOS environnement. This manual may be freely distributed in its original form. Modifications of any kind are prohibited. This manual and software are made available without warranties. TNG SOFT nor the author shall be held liable to the user or any other person or entity with respect to any liability, loss, or damage caused or alleged to be caused directly or indirectly by this manual or software. This software is shareware, and must be registered. This library is the property of the author. You are granted the rights to use only. LIBerator is a registered trademark of TNG SOFT. The original manual and software may be obtained from STARFLEET COMMAND BBS (418) 525-6899/4740/6803 FidoNet: 1:240/1701 F'req magic name > LIBERATR ▀█▀ █▀█ █▀▀ █▀▀ █▀█ █▀▀ ▀█▀ █ █ █ █▄█ ▄▄█ █▄█ █▀ █ The Next Generation Software The LIBerator 1.0 User's Guide Page 2 Chapter 1: Overview ..................................... 6 Why use LIBerator ? ..................... 6 What is LIBerator ? ..................... 6 Current version ......................... 7 A word about registration ............... 7 What's next ? ........................... 7 Chapter 2: Getting started .............................. 8 Library specifics ....................... 8 Installation ............................ 8 How to use this library ................. 9 How to use this document ................ 10 Chapter 3: Using LIBerator's templates .................. 11 Chapter 4: Using LIBerator's functions .................. 13 Chapter 5: LIBerator's standard functions <STDFCTS.H> ... 14 assert .................................. 14 arg_exist ............................... 16 arg_iexist .............................. 16 heapalloc ............................... 17 heapfree ................................ 17 Chapter 6: LIBerator's keyboard functions <KEYBFCTS.H> .. 18 getkey .................................. 18 Chapter 7: LIBerator's file functions <FILEFCTS.H> ...... 20 fnewline ................................ 20 fsize ................................... 20 fcopy ................................... 21 Chapter 8: LIBerator's screen functions <SCRFCTS.H> ..... 22 scr_vsave ............................... 22 scr_vrestore ............................ 23 scr_csave ............................... 24 scr_crestore ............................ 24 Chapter 9: LIBerator's string functions <STRFCTS.H> ..... 25 str_len ................................. 25 str_cpy ................................. 25 str_cmp ................................. 26 str_icmp ................................ 26 str_toupper ............................. 27 str_tolower ............................. 27 str_pastoc .............................. 28 str_ctopas .............................. 28 str_trim ................................ 29 str_invnames ............................ 29 The LIBerator 1.0 User's Guide Page 3 Chapter 10: LIBerator's time functions <TIMEFCTS.H> ...... 30 ticktimer_install ....................... 30 ticktimer_reset ......................... 31 ticktimer_read .......................... 31 diffdate ................................ 32 Chapter 11: LIBerator's misc functions <MISCFCTS.H> ...... 33 ansicolor ............................... 33 Appendix A: Extended keycodes ............................ 34 Appendix B: Color codes and Symbolic constants ........... 35 Appendix C: Support ...................................... 36 The LIBerator 1.0 User's Guide Page 4 This page intentionally left blank The LIBerator 1.0 User's Guide Page 5 This page intentionally left blank The LIBerator 1.0 User's Guide Page 6 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 1 Overview ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Welcome to LIBerator ! This C library is a collection of routines for the DOS environnement that were developped by TNG SOFT. Those functions are general enough to be useful in other applications. Why use LIBerator ? ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Why reinvent the wheel when someone before you created one that works quite well ? Professional programmers like to write all of there general purpose functions themselves. They want to know what's inside. But, if you're not into serious programming, and sometimes have to write short programs, LIBerator is for you. This library will give you access to useful routines that will shorten your developpement time and make your code more reliable. It will effectively free you from having to write many of the general functions your program might need. What is LIBerator ? ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Because I am big on modularity, I try to put general purpose code together in a separate function. Therefore, after developping an application, I am often left with many useful functions. Those can be recycled easily and reduce developpement time of other applications. I've decided to make this code available to everyone through this library. All those functions were tested thouroughly, and put to work in actual applications. You can be sure they'll work correctly, if you use them correctly ! All functions are FULLY documented in the following pages. The LIBerator 1.0 User's Guide Page 7 Current Version ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The complete history of LIBerator can be found in the HISTORY.TXT file, included in the archive. A word about registration ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ LIBerator is made available under the shareware concept. This means that after an evaluation period of 30 days, you should register this software with its author. Furthermore, if you use this software to create your own shareware software, YOU MUST REGISTER LIBerator. Registration grants you a life-time license to use this software, and all following versions or updates. LIBerator is NOT crippled in any way. There is absolutly no differences between the registered or unregistered version. To register this software, fill in the REGISTER.TXT registration form included in the archive. Registration is $10 CANADIAN. You will receive via 'snail mail' an official registered user certificate with your registration number. LIBerator and TNG SOFT ENTERPRISES are registered trade marks. What's Next ? ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Everytime I write a general purpose function, and think it could benefit others, I will include it in the LIBerator package. Every now and then, a new version of this library will be made public, including those new functions. I will try to improve the functions already there. I will not accept special demands. The purpose of this library is to make available code that I have in my personal library. So, that's about it for now ! Have fun and enjoy ! Rémy Gendron author of LIBerator The LIBerator 1.0 User's Guide Page 8 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 2 Getting started ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Installing and using the LIBerator library is very simple. Library specifics ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ LIBerator's functions are for the DOS environnement. They try, but do not always follow the ANSI standard. LIBerator was developped under BORLAND C++ 3.0. The code was compiled under the 'huge' memory model. All prototypes were declared as 'far' functions and all pointers were explicitely declared 'huge'. This will provide full compatibility when linking to most memory model sizes. You should consult your compiler documentation about interfacing different memory models. Unless you REALLY know what you are doing, you should always use 'huge' pointers. 'far' pointers can cause wrap around and comparison problems because they are not normalised. All LIBerator's functions use 'huge' pointers. The video output is done through direct screen writes. This makes for incredibly fast output. Going through the BIOS is just to slow. However, under multitaskers like Deskview, who often work in textmode, screen bleeds can occur if the application is running in the background. Use the virtualising options when running under DeskView. All header files use conditional compilation to prevent redeclaration errors at compile time. So, if you're not sure if a header was previously included (possibly by another header file), feel free to include it again. Installation ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Unpack the archive in a temporary directory. If you haven't done so, you should really print all of the USER'S GUIDE for easier reading. It as been formatted to print at 60 lines per pages. The LIBerator 1.0 User's Guide Page 9 Put all header files (.H) into an INCLUDE directory. Just to be sure you won't overwrite existing header files, you should make a separate include directory, then include it in the 'include' path of your compilator. Then put the LIBerator library (LIBERATR.LIB) into one of your LIBRARY directories. How to use this library ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ To use a library function, just include its header file in your source code. YOU MUST NOT write a prototype yourself based on the prototypes written in this manual. The real prototypes may have additional informations in them. So, for example: #include <stdio.h> /* A standard header file */ #include "stdfcts.h" /* A LIBerator header file */ void main (void) { ... /* Here you can use the desired function */ ... return ; } You then have to link all your modules together, including the LIBERATR.LIB library. You do that by including LIBERATR.LIB in your project. LIBERATR.LIB must be in one of your LIBRARY directories. That's all there is to it ! If you get linker errors, that's probably because you compiled your sources in C++. You must compile in C, or else make interfaces with the 'extern "C"' keyword. All arguments to functions are FULLY validated. A LIBerator function will never let you get away if it is called incorrectly. If something is wrong, the program is stopped and a plain english error message tells you what went wrong, where and why ! In the function descriptions, when it says that you SHOULD NOT or CANNOT do something, it means that if you do it, you'll get a LIBerator error message. Your program will not crash ! The LIBerator 1.0 User's Guide Page 10 How to use this document ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The following conventions are used in the document: All of LIBerator's functions were declared of type far, but the far modifier was left out of the prototypes in this manual. The following symbols are used in the text: '' Regular C and C++ keywords {} LIBerator's keywords <> Arguments to functions --> Important remarks (that you MUST read) CAPS Keyboard keys Related functions are grouped together in the same module. A chapter is devoted to each module. At the end, reference informations can be found in appendixes. I will gladly answer any questions. See the appendix 'Support' to know how to reach me ! The LIBerator 1.0 User's Guide Page 11 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 3 Using LIBerator's templates ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ LIBerator provides you with some starting templates for your programs. Templates are important to facilitate consistency in your programming style. If you already have your own style and templates, stick with them. The included templates are for new programmers, or those of you who are still searching. Of course, those are just suggestions. For instance, the usage and placement of parenthesis, currently generates many hot debates. Some will follow the 'professional' style and open a block this way : while (condition) { statements ; statements ; } While others (and I), do it this way : while (condition) { statement ; statement ; } Choose your own style ! The following files are therefore included for your convenience : MAIN.C Template for your main source file. This is the only file with a 'main' function declaration. FUNCTION.C Template for your secondary modules' code files. FUNCTION.H Template for your secondary modules' header files. STDMACRO.H Template for your standard macro definitions. Put in this file your standard macros that can be used with many different projects. --> This file contains declarations for the TRUE and FALSE macros. The LIBerator 1.0 User's Guide Page 12 PRJMACRO.H Template for macros particular to your current project. Put in this file, macros that will be needed by many modules. You should place macros specific to a module in the module's local macros section. STDTYPE.H Template for your standard type definitions. Put in this file your standard typedefs that can be used with many different projects. --> This file contains declarations for the {bool}, {byte}, {word} and {dword} types. PRJTYPE.H Template for typedefs particular to your current project. Put in this file, typedefs that will be needed by many modules. You should place typedefs specific to a module in the module's local typedefs section. HEADTEST.C Template to test your header files. Often, they will compile correctly because some other files were included before your header. This could cause problems if you intend to use this header file elsewhere, or make them available to other programmers. Your header files should always compile alone by themselves. Test them with this file. Templates promote consistency and free you from tedious tasks. Also, having something to start with, you won't as often be afflicted by the 'blank page' syndrome ! The LIBerator 1.0 User's Guide Page 13 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 4 Using LIBerator's Functions ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ There are two types of functions in the LIBerator library. Functions available in the standard libraries, and new functions. Because I like to compile in the 'huge' memory model, all functions have been written to be of type 'far'. They will also accept 'huge' pointers without the need for a typecast. Those functions don't call the standard run-time libraries. They were entirely rewritten. There is no overhead and they are fully optimized. New functions have been written because they weren't available in the standard libraries. Some conventions have been adopted for the function names: Related functions will have the same function prefix. For instance, all string functions will begin by {str_}. --> Function declarations can use types like {bool}, {byte}, {word} and {dword}. See the file STDTYPE.H for a description of those types. A function description uses the following format: FUNCTION NAME ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Short description of this function behavior. ■ Syntax #include "header.h" ReturnType FonctionName (<param>, <param>, ...) ; YOU MUST NEVER WRITE A PROTOTYPE FOR A FUNCTION YOURSELF. ALWAYS USE THE PROPER HEADER FILES. THEY HAVE ADDITIONAL INFORMATIONS IN THEM ! ■ Remarks Parameters and usage are described here when needed. ■ Return The returned value of the function is explained here. ■ Example Examples of various calls to this function. The LIBerator 1.0 User's Guide Page 14 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 5 LIBerator's standard functions ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The declarations for LIBerator's standard functions are contained in the <STDFCTS.H> header file. Those are the truly general and often used functions that will be required by most of your modules. ASSERT ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function will ASSERTain that a <condition> is TRUE. If it is, it will return immediately with no effect, and minimum overhead. If the condition is FALSE, the program will be terminated in an orderly fashion. {assert} will clear the screen, print an error message, and terminate the program with a call to 'exit'. This closes all open files, releases any memory allocated on the heap and exit to DOS. ■ Syntax #include "stdfcts.h" void assert (bool condition, char huge *fctname, int errorcode, char huge *errortext, int exitcode, void (far *exitfct)(void)) ; ■ Remarks If <condition> evaluates to FALSE, the program will be terminated and <fctname> will be displayed. You should set <fctname> to the currently executing function. This will help find the location of the error. The LIBerator 1.0 User's Guide Page 15 You can specify an error code. If 0, the error message <errortext> will be displayed. You can also use predefined error codes. In this case, <errortext> will have no effects. Just set it to NULL. 1: "Not enough memory to create an array on the heap." 2: "Not enough memory to create a struct on the heap." 3: "Not enough memory to allocate the requested amount of bytes." 4: "Out of memory." 5: "File not found." 6: "Path not found." 7: "File access denied." 8: "Input/Output error." 9: "Unrecoverable fatal error." Then, if <exitfct> is not NULL, {assert} will call this function. Set <exitfct> to point to your 'cleanup' function. For example, if you were working with files and had made .BAK files, this function could restore the original files before termination of the program. --> <exitfct> is called before all files are closed ! This function MUST be of return type 'void' and have 'void' as argument list. {assert} will then return to DOS with an errorlevel of <exitcode>. ■ Return None ■ Example assert (nbrecord>0,"datasearch",0,"No data",1,badexit); The LIBerator 1.0 User's Guide Page 16 ARG_EXIST ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function will check if an argument was passed on the command line. Check is case sensitive. ■ Syntax #include "stdfcts.h" int arg_exist (char huge *string) ; ■ Remarks The search for the argument is case sensitive. ■ Return If the command line argument <string> exists, its index in the command line argument array will be returned. If the argument does not exist, the function will return 0. See the '_argv' keyword of your compiler for details on accessing command line arguments. ■ Example if (arg_exist ("q")) sound = FALSE ; ARG_IEXIST ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function will check if an argument was passed on the command line. Check is case insensitive. ■ Syntax #include "stdfcts.h" int arg_iexist (char huge *string) ; ■ Remarks The search for the argument is case insensitive. ■ Return If the command line argument <string> exists, its index in the command line argument array will be returned. If the argument does not exist, the function will return 0. See the '_argv' keyword of your compiler for details on accessing command line arguments. ■ Example if (arg_iexist ("bios")) directvideo = FALSE ; The LIBerator 1.0 User's Guide Page 17 HEAPALLOC ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary heapalloc replaces 'farmalloc'. ■ Syntax #include "stdfcts.h" void huge *heapalloc (dword nbytes) ; ■ Remarks Allocates <nbytes> bytes on the far heap. {dword} is an unsigned long int and is declared in STDTYPE.H. ■ Return This function returns a 'huge' pointer. Be sure the pointer variable, who will receive the pointer to the allocated memory, is of type 'huge' also. ■ Example char huge *ptr ; ptr = getheap (1024) ; HEAPFREE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Freeheap replaces 'farfree'. ■ Syntax #include "stdfcts.h" void heapfree (void huge *block) ; ■ Remarks The only difference from 'farfree' is that this function offers the convenience of accepting a 'huge' pointer as argument. ■ Return None ■ Example char huge *ptr ; ptr = heapalloc (sizeof (object)) ; // Allocate memory heapfree (ptr) ; // Free memory ptr = NULL ; // Always a good idea The LIBerator 1.0 User's Guide Page 18 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 6 LIBerator's keyboard functions ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The declarations for LIBerator's keyboard functions are contained in the <KEYBFCTS.H> header file. GETKEY ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This is a replacement for the familiar 'getch' function. ■ Syntax #include "keybfcts.h" int getkey (int filter) ; ■ Remarks One of 'getch' weakness is its inability to deal with the way extended keys are internaly represented. Those are the keys that don't have an ASCII code associated with them. For exemple, the function, arrow and editing keys all return an extended keycode. This new {getkey} function will deal with these extended keys by adding 256 to the extended key code. Appendix A lists all of the extended keycodes currently available on an extended keyboard. You MUST specify a <filter> to be used by the {getkey} function. A filter of 0 will allow any key to be read and returned by the function. You can also provide the ASCII or extended key code (remember to add 256 to the real code) of the only key allowed to be returned by the function. This provides an easy way to WAIT FOR a specific key. The function will then return with that keycode, only when that key has been pressed. --> When you call {getkey}, it will first flush the keyboard buffer of any keys already present. --> Beware of NEVER setting the filter to an impossible key entry, or you will be trapped by the {getkey} function ! ■ Return If a normal key was pressed, the returned value is an int representing the ASCII code of that key. (1-255) The LIBerator 1.0 User's Guide Page 19 If an extended key was pressed, the returned value is an int representing the extended key code plus 256. (256-396) ■ Example getkey (0) ; /* Returns the first key pressed */ getkey (13) ; /* Wait for the ENTER key */ The LIBerator 1.0 User's Guide Page 20 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 7 LIBerator's file functions ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The declarations for LIBerator's file functions are contained in the <FILEFCTS.H> header file. FNEWLINE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Go to start of next line on a text file. ■ Syntax #include "filefcts.h" int fnewline (FILE *f) ; ■ Remarks The end of a text line is marked by the character '\n'. ■ Return If the start of a new line was found, '\n' is returned. If end of file was reach before a new line, EOF is returned. ■ Example error = fnewline (text) ; FSIZE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Return the size of a file. ■ Syntax #include "filefcts.h" dword fsize (FILE *f) ; ■ Remarks On a text file, the new line character is in fact 2 bytes long. DOS stores '\n' as a combination of '\n' and '\r'. So, the length of a text file will not match the number of characters read with 'fgetc'. ■ Return {fsize} returns the size of the file in bytes as a {dword}. {dword} is defined in STDTYPE.H as an unsigned long int. ■ Example size = fsize (text) ; The LIBerator 1.0 User's Guide Page 21 FCOPY ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Copy a file. ■ Syntax #include "filefcts.h" int fcopy (char huge *srcpath, char huge *destpath, bool verify) ; ■ Remarks <srcpath> is copied to <destpath>. Paths are expressed in the form [d:][path]filename.ext. --> No wildcards are allowed. If <verify> is set to TRUE, the 2 files will then be reread and compared. This is different from the DOS verify, who don't reread the files, and is therefore a little slower. ■ Return If the copy was succesful and error free, {fcopy} returns 0. On error, 1 is returned. ■ Example error = fcopy ("autoexec.bat","autoexec.bak",1) ; The LIBerator 1.0 User's Guide Page 22 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 8 LIBerator's screen functions ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The declarations for LIBerator's screen functions are contained in the <SCRFCTS.H> header file. SCR_VSAVE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function will save the current screen and video attributes in a 'text_info' structure. It has exactly the same effects as a call to 'gettextinfo'. The difference is that it can also save the actual screen content. ■ Syntax #include "scrfcts.h" void scr_vsave (struct text_info huge *ti, char huge*huge *savedscr) ; ■ Remarks All members of the 'text_info' structure <ti> are filled with this function. <savedscr> is a huge pointer to a huge char pointer. If this argument is provided, the screen content will also be saved to a buffer in the heap, and the huge pointer to char will be set to point to this buffer. If you don't want to save the screen area, set <savedscr> to NULL. --> Cursor attributes are saved, but will not be restored by {scr_vrestore}. You must use the {scr_csave} and {scr_crestore}. ■ Return None ■ Example struct text_info ti ; char huge *scrbfr ; scr_vsave (&ti,&scrbfr) ; The LIBerator 1.0 User's Guide Page 23 SCR_VRESTORE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function will restore the current screen video mode and the text window size from a 'text_info' structure. It can also restore the screen content if it was saved by a previous call to {scr_vsave}. ■ Syntax #include "scrfcts.h" void scr_vrestore (struct text_info huge *ti, char huge*huge *savedscr) ; ■ Remarks The 'text_info' structure must have been previously filled with {scr_vsave}. The same is true for the previous screen content. --> If the screen area was not saved, set <savedscr> to NULL. The memory will be liberated when the screen content is restored. So you can't restore it more than once. ■ Return None ■ Example scr_vrestore (&ti,&scrbfr) ; The LIBerator 1.0 User's Guide Page 24 SCR_CSAVE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function will save all cursor attributes, INCLUDING THE CURSOR TYPE, in a {cur_info} structure. Those attributes are: colors, x pos, y pos and cursorshape. ■ Syntax #include "scrfcts.h" void scr_csave (struct cur_info huge *ci) ; ■ Remarks The {cur_info} structure is as follow, and is defined in "scrfcts.h". struct cur_info { unsigned char attribute ; /* Cursor colors */ unsigned char curx ; /* Cursor X position */ unsigned char cury ; /* Cursor Y position */ unsigned int curtype ; /* Cursor type */ } ; ■ Return None ■ Example struct cur_info ci ; scr_csave (&ci) ; SCR_CRESTORE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function will restore all cursor attributes, INCLUDING THE CURSOR TYPE, from a {cur_info} structure. ■ Syntax #include "scrfcts.h" void scr_crestore (struct cur_info huge *ci) ; ■ Remarks The cursor attributes must have been previously saved with {scr_csave}. ■ Return None ■ Example struct cur_info ci ; scr_csave (&ci) ; ... scr_crestore (&ci) ; The LIBerator 1.0 User's Guide Page 25 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 9 LIBerator's string functions ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The declarations for LIBerator's string functions are contained in the <STRFCTS.H> header file. STR_LEN ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This is a huge version of 'strlen'. It returns the length of a string. ■ Syntax #include "strfcts.h" size_t str_len (char huge *string) ; ■ Remarks The only difference with 'strlen' is that this function offers the convenience of accepting a huge pointer as argument. ■ Return The length of the string. The type 'size_t' is defined in <stdio.h> as an unsigned int. ■ Example length = str_len (text) ; STR_CPY ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This is a huge version of 'strcpy'. It copies a string into another, including the terminating '\0' character. ■ Syntax #include "strfcts.h" char huge *str_cpy (char huge *dest, char huge *src) ; ■ Remarks The only difference from 'strcpy' is that this function offers the convenience of accepting huge pointers as arguments. ■ Return A huge pointer to the destination string. ■ Example char huge *string ; string = heapalloc (20) ; str_cpy (string,"Hello there !") ; The LIBerator 1.0 User's Guide Page 26 STR_CMP ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This is a huge version of 'strcmp'. It compares one string to another. ■ Syntax #include "strfcts.h" int str_cmp (char huge *string1, char huge *string2) ; ■ Remarks The only difference from 'strcmp' is that this function offers the convenience of accepting huge pointers as arguments. ■ Return {str_cmp} returns a value that is : <0 if <string1> is less than <string2> =0 if <string1> is the same as <string2> >0 if <string1> is greater than <string2> ■ Example if (str_cmp (name[i],name[i+1]) > 0) { /* Invert string (bubble sort) */ } STR_ICMP ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This is a huge version of 'stricmp'. It compares one string to another, without case sensitivity. ■ Syntax #include "strfcts.h" int str_icmp (char huge *string1, char huge *string2) ; ■ Remarks The only difference from 'stricmp' is that this function offers the convenience of accepting huge pointers as arguments. ■ Return {str_icmp} returns a value that is : <0 if <string1> is less than <string2> =0 if <string1> is the same as <string2> >0 if <string1> is greater than <string2> ■ Example if (str_icmp (name[i],name[i+1]) > 0) { /* Invert string (bubble sort) */ } The LIBerator 1.0 User's Guide Page 27 STR_TOUPPER ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function translates a string to uppercase. ■ Syntax #include "strfcts.h" void str_toupper (char huge *string) ; ■ Remarks None. ■ Return None. ■ Example str_toupper (name) ; STR_TOLOWER ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function translates a string to lowercase. ■ Syntax #include "strfcts.h" void str_tolower (char huge *string) ; ■ Remarks None. ■ Return None. ■ Example str_tolower (name) ; The LIBerator 1.0 User's Guide Page 28 STR_PASTOC ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function translates a string from PASCAL to C internal format. ■ Syntax #include "strfcts.h" void str_pastoc (char huge *string) ; ■ Remarks All characters in the string will be shifted left 1 space and a '\0' will be appended at the end of the string. This is useful is you're reading records written in pascal format. ■ Return None. ■ Example str_pastoc (name) ; STR_CTOPAS ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function translates a string from C to PASCAL internal format. ■ Syntax #include "strfcts.h" void str_ctopas (char huge *string) ; ■ Remarks All characters in the string will be shifted right 1 space, overwriting the terminating '\0'. The length of the string will then be put in the first byte of the array. --> The string MUST be 255 or less characters long. This is useful is you're reading records written in pascal format, converted them to C with {str_pastoc}, then reconverting to pascal before writting to disk. ■ Return None. ■ Example str_ctopas (name) ; The LIBerator 1.0 User's Guide Page 29 STR_TRIM ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function removes leading and trailing spaces from a string. ■ Syntax #include "strfcts.h" void str_trim (char huge *string) ; ■ Remarks Useful to normalise an input. ■ Return None. ■ Example str_trim (name) ; STR_INVNAMES ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function inverts first and last names in a name string. ■ Syntax #include "strfcts.h" void str_invnames (char huge *string) ; ■ Remarks A name string is composed of 1 or more clusters of characters. Clusters are packets separated from each other by 1 or more spaces. {str_invnames} will take the first cluster and move it to the end of the string. Examples: "Remy" becomes "Remy" "Remy Gendron" becomes "Gendron Remy" "Remy J. Gendron" becomes "J. Gendron Remy" "This is some string" becomes "is some string This" This could be useful if you're doing a sort by last names then first names, but your name string are in the form first then last. ■ Return None. ■ Example str_invnames (name) ; The LIBerator 1.0 User's Guide Page 30 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 10 LIBerator's time functions ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The declarations for LIBerator's time functions are contained in the <TIMEFCTS.H> header file. TICKTIMER_INSTALL ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function installs or removes a tick counter. ■ Syntax #include "timefcts.h" void ticktimer_install (void) ; ■ Remarks Ticks are PC's clock units. They are 1/18 seconds long. The ticktimer routines will allow you to count those ticks. The first call to {ticktimer_install} will install an interrupt, whose purpose is to count ticks. A second call to the {ticktimer_install} will remove the interrupt. ■ Return None. ■ Example ticktimer_install () ; The LIBerator 1.0 User's Guide Page 31 TICKTIMER_RESET ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function resets the tick count to zero. ■ Syntax #include "timefcts.h" void ticktimer_reset (void) ; ■ Remarks After installation of the interrupt, the tick count is undefined. You must reset the count before using the {ticktimer_read} function. Also, you can reset the count to zero anytime you like. --> Using this function will introduce a random delay of up to 1/18 second. The function will wait before the beginning of the next tick before returning. This garanties that tick #1 will really be 1 tick long. ■ Return None. ■ Example ticktimer_reset () ; TICKTIMER_READ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary This function returns the current tick count. ■ Syntax #include "timefcts.h" dword ticktimer_read (void) ; ■ Remarks After installation of the interrupt, the tick count is undefined. You must reset the count before using the {ticktimer_read} function. Using this function does not resets the counter. ■ Return The number of ticks since last use of {ticktimer_reset}. {ticktimer_read} returns a {dword}. {dword} is defined in STDTYPE.H as an unsigned long int. ■ Example dword count ; ticktimer_install () ; /* Install timer */ ticktimer_reset () ; /* Reset timer to 0 */ function (argument) ; /* Call your function */ count = ticktimer_read () ; /* Get ticks count */ ticktimer_install () ; /* De-install timer */ The LIBerator 1.0 User's Guide Page 32 DIFFDATE ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Calculates absolute number of days between two dates. ■ Syntax #include "timefcts.h" dword diffdate (int day1, int month1, int year1, int day2, int month2, int year2) ; ■ Remarks day1/day2 : Days of date 1 and 2. (1-31) month1/month2 : Months of date 1 and 2. (1-12) year1/year2 : Years of date 1 and 2. (1583 and after) ■ Return The absolute number of days between the 2 dates. {diffdate} returns a {dword}. {dword} is defined in STDTYPE.H as an unsigned long int. ■ Example dword count ; count = diffdate (userday, usermonth, useryear, todayday, todaymonth, todayyear) ; The LIBerator 1.0 User's Guide Page 33 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ C H A P T E R 11 LIBerator's misc functions ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The declarations for LIBerator's miscellaneous functions are contained in the <MISCFCTS.H> header file. ANSICOLOR ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ■ Summary Converts normal background and foreground color codes to color codes for ANSI escape sequence. ■ Syntax #include "miscfcts.h" void ansicolor (int fore, int back, int huge *ansbold, int huge *ansfore, int huge *ansback) ; ■ Remarks fore, back : Standard screen colors. *ansbold : Ptr to int to return bold value. *ansfore : Ptr to int to return fore value. *ansback : Ptr to int to return back value. To interpret ANSI escape sequences, the ANSI.SYS driver must be loaded. ■ Return None. ■ Example int bold, fore, back ; ansicolor (LIGHTGREEN,BLACK,&bold,&fore,&back) ; printf ("\x1b[%d;%d;%dm",bold,fore,back) ; The LIBerator 1.0 User's Guide Page 34 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ A P P E N D I X A Extended keycodes ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Extended keycodes are returned when you press a key that doesn't have an associated ASCII code. They are represented by stuffing 2 codes into the keyboard buffer. A 0 followed by an extended key keycode in the range 0 through 255. The EasyVision {getkey} function deals with these codes by returning values (int) in the range 0 through 511. The standard ASCII codes are returned unchanged (Guess why ?). Extended keycodes are added 256 to their real value for convenience, and are returned as a single number. Here they are... 259 NUL 271 Shift-TAB 272-281 Alt Q/W/E/R/T/Y/U/I/O/P 286-294 Alt A/S/D/F/G/H/J/K/L 300-306 Alt Z/X/C/V/B/N/M 315-324 F1 to F10 327 Home 328 Up arrow key 329 Page Up 331 Left arrow key 333 Right arrow key 335 End 336 Down arrow key 337 Page Down 338-339 Ins/Del 340-349 Shift-F1 to Shift-F10 350-359 Ctrl-F1 to Ctrl-F10 360-369 Alt-F1 to Alt-F10 370 Ctrl-Print Screen 371 Ctrl-Left arrow key 372 Ctrl-Right arrow key 373 Ctrl-End 374 Ctrl-Page Down 375 Ctrl-Home 376-387 Alt 1/2/3/4/5/6/7/8/9/0/-/= 388 Ctrl-Page Up 389-390 F11/F12 391 Shift-F11 392 Shift-F12 393 Ctrl-F11 394 Ctrl-F12 395-396 Alt-F11/Alt-F12 The LIBerator 1.0 User's Guide Page 35 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ A P P E N D I X B Color Codes and Symbolic constants ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ When asked for a color argument, you must provide one of the following values. As an alternative, you can also use special MACROS, provided <conio.h> as been included. Available background colors: 0 BLACK 1 BLUE 2 GREEN 3 CYAN 4 RED 5 MAGENTA 6 BROWN 7 LIGHTGRAY Available foreground colors: 0 BLACK 8 DARKGRAY 1 BLUE 9 LIGHTBLUE 2 GREEN 10 LIGHTGREEN 3 CYAN 11 LIGHTCYAN 4 RED 12 LIGHTRED 5 MAGENTA 13 LIGHTMAGENTA 6 BROWN 14 YELLOW 7 LIGHTGRAY 15 WHITE The LIBerator 1.0 User's Guide Page 36 █████████████████████████████████████████████████████████████████ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ A P P E N D I X C Support ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ I will gladly answer any questions relating to this software. I can be reach directly by netmail. Address your message to 'Remy Gendron' or 'sysop'. All those functions have already been tested in real applications. Any comments, bug reports or suggestions will be appreciated. STARFLEET COMMAND BBS (418) 525-6899/4740/6803 FidoNet: 1:240/1701 or TNG SOFT ENTERPRISES 2480 Ave de Vitre Quebec, Quebec Canada G1J 4A6 Thank you for using this software ! Remy Gendron Author of EasyVision